CHAPTER 6 : Event Bindings |
All objects within your Visaj design can be linked together using events. Events are messages which can be sent by the action of one component and may be received by the method of another. You can specify that a particular method in a specific component is called when an action (such as a button press) occurs in one component. Once you have created an event binding in Visaj, it is immediately active in the dynamic display. You can create as many bindings as you wish and try them out straightaway.
The Event Binding Editor, described in the following section, lets you create new bindings and edit existing ones. This is a wizard which can be displayed in one of the following ways:
1. | Pressing the ![]() |
2. | Holding down the Alt or Control key while dragging from the source to the destination component. |
3. | Choosing "Add event binding" from the Method menu. |
4. | Pressing either "New" or "Edit" beneath the Event bindings list. |
Event bindings, once created, are listed on the Event bindings tab of the method editing area. Here they may be edited, re-ordered or deleted. The Event bindings list is described in the Event Bindings List section on page 86.
The Event Binding Editor, shown in Figure 6-1, is where new bindings are created and existing ones are edited.
There are five ways to display the Event Binding Editor:
1. | With the Alt or Control key held down, drag the mouse pointer from one component to another in the containment hierarchy. The Event Binding Editor then appears, primed with the first and second component as the source and destination of the binding respectively. The first event type in the list is also selected. This method can only be used to create new bindings. |
2. | Press the Event Binding Editor button ![]() |
3. | Press "New" in the Event Bindings List. The Event Binding Editor is not primed, except to show all the available components. |
4. | Press "Edit" in the Event Bindings List. You will need to select a binding from the Event Bindings List first. |
5. | Select the "Add event binding" item in the Method menu. This is exactly the same as pressing the corresponding toolbar button. |
The event binding editor shows all the components in your design, all the event types associated with the selected source component and all methods available for the selected destination component. You must make a selection in the "Source" and "Object" lists for the "Type" and "Method" lists to appear.
There are usually a large number of methods for a particular handler. To quickly locate the one you require, select the Method pane (by selecting any method within it) and type the first letters of the method you are looking for. The display scrolls to methods beginning with the letters you type.
Some handler methods may be capable of throwing an exception. This is not indicated in the event binding editor. However, if you add an event binding with one of these methods, Visaj adds a method to your class which handles the exception when thrown. The method is displayed in the class structure editor on the right of the Visaj window but its signature cannot be changed. In the generated code, this method gives you a place to add your own code for handling exceptions.
The first item in the Method list is not a method at all. This item, shown as "= [expression]", allows you to assign a property or method return value to the "Object" when an event is fired. The "Next" button becomes enabled when the assignment operator is selected. Press this button to display the parameters page of the editor - described in more detail in the Event Binding Editor: Parameters section on page 83. You should use the parameters page exactly as described even though you are specifying the source of an assignment rather than a method parameter. Remember that, as with parameters, you can only select a method return value or property which is the appropriate type. You may set a "Value" if there is an editor available for the selected type.
At the bottom of the Event Binding Editor there are five buttons: "Cancel", "<Previous", "Next>", "Finish" and "Another". The Finish and Another buttons become sensitive only when you have entered enough information for the binding to be created. The only difference between these two buttons is that pressing Finish closes the dialog whereas pressing Another leaves the dialog open on the screen.
When you select a destination method, the Next button becomes sensitive if the method has parameters. Pressing the Next button (or the Return key) displays the second page of the Event Binding Editor, as shown in Figure 6-2.
The second page of the Event Binding Editor allows you to specify values for the parameters to the destination method. The parameters are listed by their type on the left of the dialog. Each parameter is shown with a cross or tick next to it:
A value has been set for this parameter
No value has been set for this parameter
The right of the dialog contains two areas. The top area lists the ways of specifying the value of the selected parameter. The lower area contains the editor for the selected value type. The four value types are:
1. | Property |
2. | Method |
3. | Value |
4. | Code expression |
The following sub-sections describes each of the above.
This allows you to set the value of the parameter to the value of a component's property. When "Property" is selected, two scrolling lists appear in the lower area. This is shown in Figure 6-3.
The list on the left shows all the objects in your design, including the event object being passed to the listener method. Selecting one of these objects causes all the properties of this object to be displayed in the list on the right if, and only if, it is assignable to the selected parameter.
You can assign any property to a parameter of type String as all objects are converted to Strings by way of their "toString" method. Properties which are going to be coerced in this way are shown in blue type.
The property list includes "this" if the object selected from the object list can be assigned to the selected parameter.
If the object selected from the object list has no properties of the appropriate type, the message "No properties of an appropriate type" is shown in the property list.
This type of parameter value is reflected in the dynamic display as soon as the binding has been completed, except when event objects have been selected from the object list.
This option allows you to use the return value of another method in your design. When you select "Method", a text field, a button labelled "Edit" and the Method selection dialog appears. The Method Selector is shown in Figure 6-4. When you have finished selecting a method it is shown in the text field. To display the Method Selector in order to edit a previous selection, press the "Edit" button.
The left side of this dialog lists all the objects in your design. When you select an object, the area on the right lists object methods which return the same type as the selected parameter. For example, if you have selected a parameter of type "int", only methods which return an integer are listed. One of the objects which can be selected is "this" - the class currently being designed. If you have added a method to your class with a compatible return type, you will be able to select it as the method for the event binding.
If the selected method has parameters, the Next button is enabled. Pressing Next displays the parameters page of the Method selection dialog - this is identical to the parameters page of the Event binding editor and is used in exactly the same way.
Press Finish when you have selected a method or Cancel if you wish to close the dialog without selecting a method. You cannot continue working on your event binding until the Method selection dialog has been closed. The selected method is shown in the text field of the parameters page.
This is an explicit value. When this is selected, a property editor appears in the lower area for you to set the value. If the property editor is a text field, you must press the Return key after typing the text to set the value. These values are used in the dynamic display once the binding has been completed.
This allows you to type in an arbitrary value or expression for the parameter. Bindings which use these are not active in the dynamic display. A text box appears in the lower area for you to enter the code expression. You do not need to press the return key at the end of the text.
The Event Bindings List, shown in Figure 6-5, makes up part of the method editing tools in the Class Editor. To view the Events Binding List, select a method from the class structure view and choose the "Event bindings" pane from the tabbed panel. Until you define a binding, this list is empty.
Press "New" to populate this list, "Edit" to change the selected binding and "Delete" to remove it from the list.
If you have more than one method bound to a component's event, they are grouped together. Use the "Up" and "Down" buttons to re-order the methods within a particular component/event group. This order is significant because this is the order in which the event bindings are executed when the application runs. The generated code always reflects the order presented in this list. To make sure that the dynamic display also reflects any changes you may have made, rebuild the containment hierarchy by pressing the Reset button.
An event binding is marked as "INVALID" if the source or destination object of a binding has been removed from the design after the binding was created. The invalid part of the binding is shown in red. An example invalid binding is shown in Figure 6-6.
The binding remains intact, so if you paste the lost object back into the design (or press "Undo"), the binding is automatically revalidated.